<?php
# ***** BEGIN LICENSE BLOCK *****
# This file is part of "myWiWall".
# Copyright (c) 2007-2008 CRP Henri Tudor and contributors.
# All rights reserved.
#
# "myWiWall" is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License version 2 as published by
# the Free Software Foundation.
# 
# "myWiWall" is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with "myWiWall"; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
# ***** END LICENSE BLOCK *****


/**
 * The Tags model class provides you services allowing you to access persistant
 * data relevant to the 'Widget Tags'. It provides for instance, a method to
 * retrieve all tags in the database, the tags relevant to a given widget, ...
 * 
 * @author Laurent Haan <laurent.haan@gmail.com>
 * @author J�r�me Bogaerts <jerome.bogaerts@gmail.com>
 * @package mywiwall.models
 *
 */
class Tags
{
	/**
	 * Retrieve all tags with their counter (e.g tag=foo, counter=3) from
	 * the persistent data stored in database.
	 *
	 * @param integer $limit The maximum count of elements in the result list.
	 * @param string $format only 'json' or 'raw' formats are allowed.
	 * @return mixed a json structure or an array containing the tags and their counter.
	 */
	public static function retrieveAllTags($limit, $format = 'json')
	{
		$format = strtolower($format);
		if ($format != 'json' && $format != 'raw')
			throw new Exception('Only json and raw format are provided by Tags::retrieveAllTags.');

		$db = DbUtil::accessFactory();	
			
		// Sanitize data and execute !
		$rs = $db->select("SELECT COUNT(*) AS `counter`, `tag` FROM `widget_tags` GROUP BY `tag` ORDER BY `counter` DESC, `tag` ASC LIMIT 0, ${limit}");
		
		// Read the the result set into an associative array.
		$obj = array();
		while($rs->fetch())
			$obj[$rs->tag] = $rs->counter;
			
		uksort($obj, 'strcasecmp');
		
		switch ($format)
		{
			case 'json':
			
				return json_encode($obj);
				break;
				
			case 'raw':
			default:
				return $obj;
				break;
		}
	}
	
	/**
	 * Retrieves all tags for a given widget  in a 'json' or 'raw' format.
	 *
	 * @param string $widgetId The widget's database identifier.
	 * @param string $format The output format. Only 'json' and 'raw' are accepted.
	 * @return mixed All the tags associated with a given widget as json or array.
	 */
	public static function retrieveWidgetTags($widgetId, $format = 'json')
	{
		
		$format = strtolower($format);
		if ($format != 'json' && $format != 'raw')
			throw new Exception('Only json and raw format are provided by Tags::retrieveWidgetTags.');
		
		$db = DbUtil::accessFactory();
			
		// Sanitize data and execute the statement.
		$widgetId = $db->escape($widgetId);
		$rs = $db->select("SELECT `tag` FROM `widget_tags` WHERE `widget` = '${widgetId}' ORDER BY `tag` ASC");
		
		switch ($format)
		{
			case 'json':
				$obj = array('widget' => $widgetId, 'tags' => '');
		
				// Read the the result set into an associative array.
				while ($rs->fetch())
					$obj['tags'] .= " " . $rs->tag;

				return json_encode($obj);
				break; // defensive.
				
			case 'raw':
			default:
				$obj = array();
				
				while($rs->fetch())
					$obj[] = $rs->tag;
					
				return $obj;
				break; // defensive.
		}
	}
	
	/**
	 * Returns a list of tags contained in the database following a given prefix.
	 * 
	 * Example : the database contains these tags -> obiwan, yoda, luke, han, leia, yoghurt.
	 *           If you give 'yo' to this function you will receive array('yoda', 'yoghurt').
	 *
	 * @param string $tagPrefix A prefix that must match the resulting tags.
	 * @return array an array of tags as strings.
	 */
	public static function searchForTags($tagPrefix)
	{
		$db = DbUtil::accessFactory();
		
		// Sanitization and query execution.
		$tagPrefix = $db->escape($tagPrefix);
		$rs = $db->select("SELECT `label` FROM `tags` WHERE `label` LIKE '${tagPrefix}' ORDER BY `label` ASC LIMIT 0, 10");
		
		// Read the the result set into an associative array.
		$tags = array();
		while($rs->fetch())
			$tags[] = $rs->label;
			
		return $tags;
	}
}
?>